How to compile PyQt6 or PySide6 code with Nuitka

Nuitka is a Python compiler that translates your Python code into C, then compiles it into a native executable. For PyQt6 and PySide6 applications, this means you can distribute your GUI app as a standalone program — no Python installation required on the target machine. The compiled output runs natively, which can also bring performance improvements over interpreted Python.

In this tutorial, we'll walk through the process of compiling a PyQt6 or PySide6 application with Nuitka on Windows. We'll cover installing Nuitka, setting up a C compiler, and running the right command to produce a working standalone executable with Qt plugins included.

What Nuitka gives you

Before we start, here's a quick summary of what Nuitka brings to the table:

• Native compilation — your Python code is converted to C and compiled, producing a real executable
• Standalone packaging — bundle everything needed so users don't need Python installed
• Cross-platform support — works on Windows, macOS, and Linux
• Multiple compiler backends — supports MSVC, MinGW, and Clang
• Wide Python version support — works with Python 2.7 and Python 3.4 through 3.8+
• Both 32-bit and 64-bit — compile for x86, x64, and even ARM targets

Installing Nuitka

First, install Nuitka from PyPI using pip:

pip install nuitka

This gives you the nuitka command-line tool, which handles the entire compilation process.

Setting up a C compiler

Nuitka needs a C compiler to turn the generated C code into a native executable. On Windows, you have two main options: MinGW or Microsoft Visual Studio (MSVC).

Option A: MinGW (lightweight)

If you don't want to install Visual Studio, MinGW is a good lightweight option. Download the version that matches your Python installation:

• MinGW 64-bit — for 64-bit Python
• MinGW 32-bit — for 32-bit Python

Extract the archive, then add the mingw\bin folder to your system's PATH environment variable. You can do this through System Properties > Environment Variables on Windows, or temporarily in your terminal:

set PATH=C:\path\to\mingw64\bin;%PATH%

To verify it's working, open a new terminal and run:

gcc --version

You should see version information for GCC printed out.

Option B: Visual Studio (MSVC)

If you already have Visual Studio 2019 or later installed (or are willing to install it), Nuitka will detect and use the MSVC compiler automatically. Make sure you've installed the "Desktop development with C++" workload through the Visual Studio Installer.

This is a larger download, but some users find it more reliable for compiling Qt applications on Windows.

Preparing your code

Before compiling, make sure your PyQt6 or PySide6 application runs correctly from the command line. Nuitka compiles what you give it, so any bugs in your Python code will still be present in the compiled version.

Let's say you have a simple application in main.py:

import sys
from PyQt6.QtWidgets import QApplication, QMainWindow, QLabel

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("My Compiled App")
        label = QLabel("Hello from Nuitka!")
        label.setMargin(20)
        self.setCentralWidget(label)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec_()

Or the PySide6 equivalent:

import sys
from PySide6.QtWidgets import QApplication, QMainWindow, QLabel

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("My Compiled App")
        label = QLabel("Hello from Nuitka!")
        label.setMargin(20)
        self.setCentralWidget(label)

app = QApplication(sys.argv)
window = MainWindow()
window.show()
app.exec_()

Run it first with python main.py to confirm everything works as expected.

Compiling with Nuitka

Now for the actual compilation. The command you use depends on which Qt plugins your application needs.

Including all Qt plugins

If you want to make sure everything works and aren't concerned about output size, include all Qt plugins:

nuitka main.py --show-progress --recurse-all --standalone --plugin-enable=qt-plugins --include-qt-plugins=all --windows-disable-console

Let's walk through what each flag does:

This compilation will take a few minutes. Nuitka is translating your entire application (and its dependencies) to C, then compiling everything. The --show-progress flag helps you see that things are moving along.

Including only specific Qt plugins

For a smaller output, you can include only the plugins you actually need. For most applications, the sensible set plus styles covers what's required:

nuitka main.py --show-progress --recurse-all --standalone --plugin-enable=qt-plugins --include-qt-plugins=sensible,styles --windows-disable-console

The sensible option includes the platform and essential plugins that Qt needs to run, while styles adds the visual style plugins that make your application look native on Windows.

Finding your compiled application

After compilation finishes, Nuitka creates a main.dist folder (named after your script) in the current directory. Inside that folder you'll find main.exe along with all the DLLs and resources needed to run your application.

You can distribute this entire folder to users. They won't need Python or PyQt6/PySide6 installed — everything is bundled together.

Troubleshooting: missing Qt plugins

If your compiled application starts but shows a blank window, crashes on launch, or fails to load images, you may be missing some Qt plugins. This is the most common issue when compiling Qt applications.

The fix is to copy the missing plugin folders from your PySide6 or PyQt6 installation into the main.dist output folder. The folders you're most likely to need are:

• platforms — required for the application to display a window at all
• imageformats — needed if your app loads PNG, JPEG, or other image files
• styles — needed for native-looking widgets

You can find these folders in your Python environment's site-packages directory. For example:

C:\Python311\Lib\site-packages\PySide6\plugins\platforms
C:\Python311\Lib\site-packages\PySide6\plugins\imageformats

Or for PyQt6:

C:\Python311\Lib\site-packages\PyQt6\Qt\plugins\platforms
C:\Python311\Lib\site-packages\PyQt6\Qt\plugins\imageformats

Copy the relevant folders into your main.dist directory, and your application should work correctly.

Viewing available Nuitka plugins

To see what plugins Nuitka supports beyond Qt, run:

nuitka --plugin-list

This prints a list of all available plugins with brief descriptions. Plugins exist for various libraries like NumPy, TensorFlow, and more — so if your application uses other packages, check whether a dedicated plugin exists.

Summary

Compiling PyQt6 and PySide6 applications with Nuitka gives you native executables that are easy to distribute and can run faster than interpreted Python. The process comes down to three steps: install Nuitka, set up a C compiler, and run the compilation command with the right Qt plugin flags.

For quick reference, here's the command that works for most Qt applications:

nuitka main.py --show-progress --recurse-all --standalone --plugin-enable=qt-plugins --include-qt-plugins=sensible,styles --windows-disable-console

If you run into display issues with the compiled output, copying the platforms and imageformats folders from your Qt installation into the output directory will usually resolve them.